What ☑️

Stage 1 (groundwork) of client configuration reporting for the 3.x driver — the 3.x counterpart of the 4.x feature. It lets the driver report its effective client configuration to ScyllaDB at connection time, so operators can inspect driver settings (via system.clients.client_options) while investigating incidents. Follows the cross-driver JSON schema design.

This is phase 1 of 2 — it lands the plumbing; the full configuration report (all groups) comes in phase 2 (#974).

Behavior 👶

Two STARTUP options are added:

• SESSION_ID — a dedicated, driver-generated UUID, sent on every connection (control and pool), unconditionally — like the DRIVER_NAME / DRIVER_VERSION options the driver already always sends. One id per Cluster, shared by every connection opened from it — including across multiple Sessions obtained from the same Cluster — so the server can group them. It's Cluster-scoped rather than Session-scoped because the control connection isn't tied to any particular Session (see discussion in review). Independent of the user-settable CLIENT_ID.
• DRIVER_CONFIG — a compact JSON blob, sent only on the control connection. Enabled by default; opt out with Cluster.builder().withDriverConfigReporting(false). Stage 1 emits only {"version":1}; the full report follows in phase 2. system.clients.client_options is per node, so only the node holding the control connection stores this — consumers must query and aggregate across all nodes to see the full picture.

The report is built once, while the Cluster initializes, and the resulting string is reused for every control connection that Cluster opens — it is never rebuilt while the session is in flight, so a control-connection reconnect costs nothing and always reports the same configuration. Building it is fail-safe: any failure is swallowed and simply leaves DRIVER_CONFIG unset rather than breaking cluster initialization.

Changes ✍️

• New DriverConfigReporter / DefaultDriverConfigReporter (package com.datastax.driver.core) build the DRIVER_CONFIG payload — a single buildReport() call that returns the JSON, or null if it couldn't be built.
• Connection.Factory (one per Cluster) holds that cluster's SESSION_ID and, when reporting is enabled, the report built at initialization time. It hands the report to the control connection as a constructor argument — null everywhere else, and null is exactly what suppresses DRIVER_CONFIG. No reporter instance is retained, and none is constructed at all when reporting is off.
• Both options are written in Connection.onOptionsReady(), right after the existing applicationInfo startup-option hook.
• The control connection is identified by threading a reportConfig flag from ControlConnection.tryConnect through a new Connection.Factory.open(host, reportConfig) overload — 3.x has no pre-existing signal that identifies the control connection at STARTUP time.
• New config flag threaded through Cluster.Builder → Configuration.Builder → Configuration (default true).
• jackson-core/jackson-databind are enforced as plain required dependencies (as they already were in released 3.11.5.17), used by DefaultDriverConfigReporter to build the JSON blob; the orphaned jackson-dataformat-yaml dependency (dead since the Scylla Cloud config code was removed) is dropped, so consumers no longer inherit SnakeYAML. OSGi manifests carry mandatory com.fasterxml.jackson.*;version="[2.18,3)" imports accordingly.

Testing 🔨

Unit tests

• DefaultDriverConfigReporterTest: reporting is enabled by default (both Configuration.builder() and Cluster.builder()), the stage-1 report is {"version":1}, and report building is fail-safe (a throwing build yields null instead of propagating).
• driver-core compiles and unit tests are green.

Integration tests

DriverConfigReportingCcmTest (live ScyllaDB, @ScyllaVersion ≥ 2026.1; named *Test rather than *IT so Surefire's default discovery actually picks it up — see review discussion) asserts what the server stores in system.clients:

• SESSION_ID is stored for every connection of the cluster, and DRIVER_CONFIG for exactly one (the control connection);
• two Sessions opened from the same Cluster share one SESSION_ID;
• with reporting disabled, SESSION_ID is still stored but DRIVER_CONFIG is not.

The cluster under test uses the default configuration (no withDriverConfigReporting call), so these also cover default-on end-to-end. Each cluster's connections are identified by the SESSION_ID the driver generated for it, so the assertions can't be confused by another cluster's rows. The end-to-end verification of the full report lands with phase 2.

Verified live against ScyllaDB 2026.1 — all 3 methods pass.

Manual tests 🖐

Captured the actual STARTUP frames on the wire with tshark, against a live single-node ScyllaDB 2026.1.0 (CCM), to directly confirm the plumbing — same method as #967's stage-1 verification for the 4.x driver.

Environment: single node ScyllaDB 2026.1.0 on CCM, contact point 127.0.0.1:9042, minimal Cluster.builder().addContactPoint("127.0.0.1").withPort(9042) — samples 1 and 2 with no withDriverConfigReporting call at all (i.e. the default), sample 3 with withDriverConfigReporting(false).

Sample 1: Control connection STARTUP frame (default configuration)

Cassandra CQL Protocol
    Version: 0x04
        .... 0100 = Protocol version: 4
        0000 .... = Direction: Request (0x0)
    Stream Identifier: 64
    .000 0001 = Opcode: STARTUP (1)
    Message Length: 264
    Message STARTUP
        String Map Size: 8
        String Length: 13
        String: DRIVER_CONFIG
        String Length: 13
        String: {"version":1}
        String Length: 28
        String: SCYLLA_LWT_ADD_METADATA_MARK
        String Length: 11
        String: -2147483648
        String Length: 22
        String: SCYLLA_USE_METADATA_ID
        String Length: 0
        String: 
        String Length: 18
        String: TABLETS_ROUTING_V1
        String Length: 0
        String: 
        String Length: 10
        String: SESSION_ID
        String Length: 36
        String: d5c0ea79-22bb-4e60-bc49-cf078e1599d7
        String Length: 11
        String: CQL_VERSION
        String Length: 5
        String: 3.0.0
        String Length: 14
        String: DRIVER_VERSION
        String Length: 18
        String: 3.11.5.18-SNAPSHOT
        String Length: 11
        String: DRIVER_NAME
        String Length: 20
        String: ScyllaDB Java Driver

Sample 2: Pool connection STARTUP frame (default configuration)

Cassandra CQL Protocol
    Version: 0x04
        .... 0100 = Protocol version: 4
        0000 .... = Direction: Request (0x0)
    Stream Identifier: 64
    .000 0001 = Opcode: STARTUP (1)
    Message Length: 234
    Message STARTUP
        String Map Size: 7
        String Length: 28
        String: SCYLLA_LWT_ADD_METADATA_MARK
        String Length: 11
        String: -2147483648
        String Length: 22
        String: SCYLLA_USE_METADATA_ID
        String Length: 0
        String: 
        String Length: 18
        String: TABLETS_ROUTING_V1
        String Length: 0
        String: 
        String Length: 10
        String: SESSION_ID
        String Length: 36
        String: d5c0ea79-22bb-4e60-bc49-cf078e1599d7
        String Length: 11
        String: CQL_VERSION
        String Length: 5
        String: 3.0.0
        String Length: 14
        String: DRIVER_VERSION
        String Length: 18
        String: 3.11.5.18-SNAPSHOT
        String Length: 11
        String: DRIVER_NAME
        String Length: 20
        String: ScyllaDB Java Driver

Sample 3: Control connection STARTUP frame (withDriverConfigReporting(false))

Cassandra CQL Protocol
    Version: 0x04
        .... 0100 = Protocol version: 4
        0000 .... = Direction: Request (0x0)
    Stream Identifier: 64
    .000 0001 = Opcode: STARTUP (1)
    Message Length: 234
    Message STARTUP
        String Map Size: 7
        String Length: 28
        String: SCYLLA_LWT_ADD_METADATA_MARK
        String Length: 11
        String: -2147483648
        String Length: 22
        String: SCYLLA_USE_METADATA_ID
        String Length: 0
        String: 
        String Length: 18
        String: TABLETS_ROUTING_V1
        String Length: 0
        String: 
        String Length: 10
        String: SESSION_ID
        String Length: 36
        String: c9906f24-99df-4874-aeee-a87a00068d41
        String Length: 11
        String: CQL_VERSION
        String Length: 5
        String: 3.0.0
        String Length: 14
        String: DRIVER_VERSION
        String Length: 18
        String: 3.11.5.18-SNAPSHOT
        String Length: 11
        String: DRIVER_NAME
        String Length: 20
        String: ScyllaDB Java Driver

Note on cross-driver consistency ⚠️

The merged 4.x stage 1 (#967) currently differs from what this PR now does, on three points requested in review here: it ships disabled by default (advanced.driver-config-reporting.enabled = false), it gates SESSION_ID behind that same flag, and it rebuilds the blob on every control-connection init. Happy to align 4.x in a follow-up if we want the two drivers to behave identically — just say the word and I'll open it.

Follow-up (phase 2)

• Populate the full configuration report (connection / socket / policies / connection pool / query defaults / tls) per the approved v2 schema.

Fixes DRIVER-382

🤖 Generated with Claude Code